---
title: Consumption
summary: How a consuming application references, constructs, and calls PdfAPI.Client.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-09-17
---

# Consumption

A consumer references the `PdfAPI.Client` package, constructs `PdfClient` once with a `ClientInfo` and a base URL, and calls its members directly — no registration with a DI container was found in any consumer observed in scope.

## Package reference

| Field | Value |
| --- | --- |
| Package id | `PdfAPI.Client` |
| Version | `1.0.0.3` |
| Reference style | `packages.config` |
| Target framework | .NET Framework v4.6.2 |

Installing the package also installs the client and `PdfAPI.Core` contracts **source** under `src\`. See [Package](package.md) for what that means for the consumer.

## Construction

```csharp
var info = new ClientInfo();
var client = new PdfAPI.Client.PdfClient(info, url);
```

Every consumer observed in scope passes a default-constructed, empty `ClientInfo` — no `ApplicationId`, `MachineName`, or `UserId` is set by any caller in this repository (`PdfApiClientTester\PdfApiClientTester\PdfTester.cs:23`).

| Step | Requirement |
| --- | --- |
| Base URL | Read from configuration key `pdfapi.url` via `IEnvironmentService.GetConfigSetting("pdfapi.url")` in every consumer observed in scope |
| `ClientInfo` | Supplied by the consumer; `PdfClient` sets no property of its own |
| Initialization | Single constructor — no follow-up initializer method exists or is required |

### Dependency injection

No consumer in this repository registers `IPdfClient` with an Autofac `ContainerBuilder`; every observed consumer constructs `PdfClient` directly with `new`.

| Registration | Lifetime | Notes |
| --- | --- | --- |
| `IPdfClient` → `PdfClient` | — | No registration found in surveyed consumers |

## Resilience

| Concern | Finding | Configurable by consumer | Source | Tech debt |
| --- | --- | --- | --- | --- |
| Timeout | None configured — inherits the `JsonHttpClient` default; the default value could not be verified from source available to this run** | No | `PdfAPI.Client\PdfClient.cs:18` | Yes |
| Retry | None configured | No | — | Yes |
| Circuit breaking | None configured | No | — | Yes |
| Thread safety | Safe for concurrent use — `PdfClient` has a single constructor, no two-phase initialization, and a `readonly` `JsonHttpClient` field, so an instance is immutable after construction | — | `PdfAPI.Client\PdfClient.cs:12-19` | No |
| Cancellation | Not supported — no `CancellationToken` parameter on any member | — | `PdfAPI.Client\IPdfClient.cs`, `PdfAPI.Client\PdfClient.cs` | Yes |

The constructor `new JsonHttpClient(baseUri, info)` omits the timeout argument entirely, so whatever default `JsonHttpClient` applies is what governs every call — a consumer that needs a bounded call duration must wrap calls in its own outer timeout. There is no retry loop anywhere in `PdfAPI.Client`, so a consumer that needs resilience to transient HTTP failures must implement its own retry around every call. No `CancellationToken` exists on any member, so an in-flight call cannot be abandoned by the caller. See [Tech debt](tech-debt.md).

## Error handling for consumers

| Failure | Surfaces as | Consumer action |
| --- | --- | --- |
| API unreachable | Exception from `JsonHttpClient`'s underlying transport — not caught or wrapped by `PdfClient` | Catch and handle at the call site |
| Non-success status | Exception from `JsonHttpClient` — not caught or wrapped by `PdfClient` | Catch and handle at the call site |
| Timeout exceeded | Exception from `JsonHttpClient`'s transport default | Catch and handle at the call site |
| Empty result set | `null` (`Convert`, `Merge`) or `false` (`IsPdfa`) returned silently via `.Results.FirstOrDefault()` — no exception raised | Treat a `null`/`false` result as ambiguous between "genuinely empty" and "call failed silently" |

## Usage examples

```csharp
// Construct the client and convert a request-shaped document
var info = new ClientInfo();
var client = new PdfAPI.Client.PdfClient(info, envSvc.GetConfigSetting("pdfapi.url"));
var result = client.Convert(new ConvertRequest());
```

| Scenario | Members used | Notes |
| --- | --- | --- |
| Convert a document by request | `Convert(ConvertRequest)` | Drawn from `PdfAPI.Client.Tests\PdfClientTests.cs` construction pattern |
| Check whether bytes are a PDF, locally | `IsPdf(byte[])` | No network call; runs entirely in the consumer's process |
| Poll a tracked request's status | `Track(long)` | Single immediate read; the API's own retry defaults apply because `PdfClient` passes neither `retryIntervalMilliseconds` nor `retryCount` |

## Lifecycle guidance

| Question | Answer |
| --- | --- |
| Construct once or per call | Construct once and reuse — the client holds no per-call state and is immutable after construction |
| Disposable | No (`IPdfClient`/`PdfClient` do not implement `IDisposable`) |
| Safe to share across threads | Yes — see the Resilience table's thread-safety finding |

## Related documentation
- [Client index](index.md)
- [Overview](overview.md)
- [Architecture](architecture.md)
- [Package](package.md)
- [Client reference](reference.md)
- [Endpoint map](endpoint-map.md)
- [Contracts](contracts.md)
- [Dependencies](dependencies.md)
- [Business rules](business-rules.md)
- [Tech debt](tech-debt.md)

> **Note:** Statements marked with `**` could not be confirmed; treat as unknown until
> verified.

## Sources
- `PdfAPI.Client\PdfClient.cs`
- `PdfAPI.Client\IPdfClient.cs`
- `PdfApiClientTester\PdfApiClientTester\PdfTester.cs`
- `PdfAPI.Client.Tests\PdfClientTests.cs`